home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / wais / doc / question.txt < prev    next >
Text File  |  1995-05-09  |  4KB  |  162 lines
  1.  
  2.  
  3.               Question Description Structures
  4.  
  5.                        Harry Morris morris@think.com
  6.             Jonathan Goldman jonathan@think.com
  7.                   3/2/91
  8.  
  9.  
  10. A "question description structure" is used by a client of the WAIS system
  11. to pose a query to a WAIS server.  This document describes a text encoding
  12. of the question description structure.  This specification is compatible
  13. with the clients that are given out with the WAIS release (version 8 and
  14. higher).  Example C code to read and write these structures is available
  15. free of charge from the authors.
  16.  
  17. Note that WAIS end users should never see this structure, since a typical
  18. user will use the questions created by a client, and interact with them
  19. through a client user interface.
  20.  
  21. Philosophy: -----------
  22.  
  23. Questions are the basic way a user interacts with a WAIS server.  We have
  24. found it useful to store the current state of a particular interaction
  25. (hereafter referred to simply as the question), so that it may be used
  26. later, either by the user explicitly, or by a smart client to submit
  27. requests to the server automatically.
  28.  
  29. The other fields are strictly optional.  Clients may choose to let the user
  30. store additional parameters in questions (eg. how to display the question).
  31. While not all clients may want or need all the optional fields, it is in
  32. everyone's best interest to have any particular function expressed in a
  33. single format that all can share.  The optional fields presented here are
  34. ones we have found useful.  If you have suggestions for fields that should
  35. be added to the specification, please contact the authors.
  36.  
  37. Clients and servers should always be prepared to ignore the non-required
  38. fields.
  39.  
  40. Question structure have four basic parts:
  41.  
  42. 1.  The search words upon which the question is based
  43. 2.  The sources to search
  44. 3.  Some documents that might be similar to the desired results.
  45. 4.  The resulting documents as returned from the sources.
  46. 5.  Optional fields
  47.  
  48. An example of a question structure:
  49.  
  50. (:question 
  51.  :version  1 
  52.  :seed-words "how do I use the wais system?"
  53.  :relevant-documents (  ) 
  54.  :sources 
  55.  ( (:source-id 
  56.     :filename "wais-docs" ) 
  57.    (:source-id
  58.     :filename "CMNS")
  59.  ) 
  60.  :result-documents  (  ) 
  61. ) 
  62.  
  63. The first symbol in the structure must be :question, as this identifies the
  64. structure.  The rest of the symbols may appear in any order.  They are:
  65.  
  66.  
  67. Syntax:
  68. ------
  69.  
  70. See the syntax discussion in source.txt
  71.  
  72.  
  73. Fields:
  74. ------
  75.  
  76. :version <integer>  
  77. The number is the major version number of the question structure format.
  78. The current version is 2.  This must be the first slot.
  79.  
  80. :seed-words <string>
  81. These are the search keywords requested by the user.
  82.  
  83. :sources  <list>
  84. A (possibly empty) list of source-id structures.  Source-ids identify the
  85. sources which the question will use.  They point to a file containing a
  86. source structure (see source.txt).  They are defined as:
  87.  
  88.     (:source-id
  89.          :filename <string>
  90.     )
  91.  
  92. :relevant-documents <list>
  93. A (possibly empty) list of document-id structures.  They are documents
  94. which the user has selected as "relevant" to the query.  Some servers can
  95. use the information contained in relevant documents to drastically improve
  96. search performance.  They are defined below.
  97.  
  98. :result-documents <list>
  99. Another (possibly empty) list of document-id structures.  These constitute
  100. the answers provided to the question by the server(s) it refers to.
  101.  
  102. :sort-results-by <sort-type>
  103. A hint to the client as to how to sort the result documents for display.
  104. Sort-type is one of
  105.  
  106.     :score 
  107.     :date
  108.     :source - alphabetically
  109.  
  110. :window-geometry  <rect>
  111. The positioning of the question editing window (if there is one) in machine
  112. dependent units.  It is of the form
  113.     
  114.     (:rect  
  115.         :left    <integer>
  116.         :top      <integer>  
  117.         :right  <integer>  
  118.         :bottom <integer>
  119.         ) 
  120.  
  121.  
  122. Document-id Structure Definition:
  123. --------------------------------
  124.  
  125.  
  126. (:document-id
  127.     :score            <integer>
  128.     :start            <fragment>
  129.     :end            <fragment>
  130.     :document         <document>
  131.     )
  132.  
  133. (:fragment
  134.     either
  135.     :byte-pos        <integer>
  136.     or
  137.     :line-pos        <integer>
  138.     or
  139.     :para-id        <integer>
  140.     )
  141.  
  142. (:document
  143.     :headline         <string>
  144.     :doc-id         <doc-id>
  145.     :source         <source-id>
  146.     :number-of-lines     <integer>
  147.     :number-of-bytes     <integer>
  148.     :best-line         <integer>
  149.     :type             <string>
  150.     :date             <string>
  151.     )
  152.  
  153. (:doc-id
  154.     :original-server    <any>
  155.     :original-database    <any>
  156.     :original-local-id     <any>
  157.     :distributor-server    <any>
  158.     :distributor-database    <any>
  159.     :distributor-local-id     <any>
  160.     :copyright-disposition  <number> 
  161.     )
  162.